IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/u_man/cat3/Tcl/memory.z/memory

Text File | 2002-10-03 | 17.0 KB | 331 lines

MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))                                                      MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))



NNNNAAAAMMMMEEEE
     ckalloc, memory, ckfree, Tcl_DisplayMemory, Tcl_InitMemory,
     Tcl_ValidateAllMemory - Validated memory allocation interface.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     mmmmeeeemmmmoooorrrryyyy iiiinnnnffffoooo

     mmmmeeeemmmmoooorrrryyyy ttttrrrraaaacccceeee [oooonnnn||||ooooffffffff]

     mmmmeeeemmmmoooorrrryyyy vvvvaaaalllliiiiddddaaaatttteeee [oooonnnn||||ooooffffffff]

     mmmmeeeemmmmoooorrrryyyy ttttrrrraaaacccceeee____oooonnnn____aaaatttt____mmmmaaaalllllllloooocccc _n_n_n

     mmmmeeeemmmmoooorrrryyyy bbbbrrrreeeeaaaakkkk____oooonnnn____mmmmaaaalllllllloooocccc _n_n_n

     mmmmeeeemmmmoooorrrryyyy ddddiiiissssppppllllaaaayyyy _f_i_l_e



     #include <tcl.h>

     char *
     ckalloc (unsigned size)

     void
     ckfree (char *ptr)

     int
     Tcl_DumpActiveMemory (char *fileName);

     void
     Tcl_ValidateAllMemory (char *file,
                            int   line)

     void
     Tcl_InitMemory (interp)

AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
     A pointer to the Tcl interpreter.  The filename of the caller of
     Tcl_ValidateAllMemory.  The line number of the caller of
     Tcl_ValidateAllMemory.  File to display list of active memory.


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
   cccckkkkaaaalllllllloooocccc
     Thi macro allocates memory, in the same manner as mmmmaaaalllllllloooocccc, with the
     following differences: One, cccckkkkaaaalllllllloooocccc checks the value returned from mmmmaaaalllllllloooocccc
     (it calls mmmmaaaalllllllloooocccc for you) and panics if the allocation request fails.
     Two, if enabled at compile time, a version of cccckkkkaaaalllllllloooocccc with special memory
     debugging capabilities replaces the normal version of cccckkkkaaaalllllllloooocccc, which aids
     in detecting memory overwrites and leaks (repeated allocations not
     matched by corresponding frees).



                                                                        PPPPaaaaggggeeee 1111






MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))                                                      MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))



     Parameters:
       oooo _s_i_z_e - The size of the memory block to be allocated.

     Returns:
       A pointer to the allocated memory block.

   cccckkkkffffrrrreeeeeeee
     This macro frees memory allocated by cccckkkkaaaalllllllloooocccc.  Like cccckkkkaaaalllllllloooocccc, when memory
     debugging is enabled, cccckkkkffffrrrreeeeeeee has enhanced capabilities for detecting
     memory overwrites and leaks.

     It is very important that you use cccckkkkaaaalllllllloooocccc when you need to allocate
     memory, and that you use cccckkkkffffrrrreeeeeeee to free it.  Should you use mmmmaaaalllllllloooocccc to
     allocate and cccckkkkffffrrrreeeeeeee to free, spurious memory validation errors will occur
     when memory debugging is enabled.  Should you use ffffrrrreeeeeeee to free memory
     allocated by cccckkkkaaaalllllllloooocccc, memory corruption will occur when memory debugging
     is enabled.  Any memory that is to be become the property of the Tcl
     interpreter, such as result space, must be allocated with cccckkkkaaaalllllllloooocccc.  If it
     is absolutely necessary for an application to pass back mmmmaaaalllllllloooocccced memory
     to Tcl, it will work only if Tcl is complied with the TTTTCCCCLLLL____MMMMEEEEMMMM____DDDDEEEEBBBBUUUUGGGG flag
     turned off.  If you convert your application to use this facility, it
     will help you find memory over runs and lost memory.  Note that memory
     allocated by a C library routine requiring freeing should still be freed
     with ffffrrrreeeeeeee, since it calls mmmmaaaalllllllloooocccc rather than cccckkkkaaaalllllllloooocccc to do the
     allocation.

     Parmaters:
       oooo _p_t_r - The address of a block to free, as returned by ckalloc.


   TTTTccccllll____DDDDuuuummmmppppAAAAccccttttiiiivvvveeeeMMMMeeeemmmmoooorrrryyyy
     This function will output a list of all currently allocated memory to the
     specified file.  The following information is outputed for each allocated
     block of memory: starting and ending addresses (excluding guard zone),
     size, source file where cccckkkkaaaalllllllloooocccc was called to allocate the block and line
     number in that file.  It is especially useful to call
     TTTTccccllll____DDDDuuuummmmppppAAAAccccttttiiiivvvveeeeMMMMeeeemmmmoooorrrryyyy after the Tcl interpreter has been deleted.

     Parameters:
       oooo _f_i_l_e_N_a_m_e - The name of the file to output the memory list to.

   TTTTccccllll____VVVVaaaalllliiiiddddaaaatttteeeeAAAAllllllllMMMMeeeemmmmoooorrrryyyy
     Forces a validation of the guard zones of all currently allocated blocks
     of memory.  Normally validation of a block occures when its freed, unless
     full validation is enabled, in which case validation of all blocks occurs
     when cccckkkkaaaalllllllloooocccc and cccckkkkffffrrrreeeeeeee are called.  This function forces the validation
     to occur at any point.

     Parameters:
       oooo _f_i_l_e - The file that this routine is being called from, normally
       ________FFFFIIIILLLLEEEE________.
       oooo _l_i_n_e - The line that this routine is being called from, normally



                                                                        PPPPaaaaggggeeee 2222






MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))                                                      MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))



       ________LLLLIIIINNNNEEEE________.

EEEENNNNAAAABBBBLLLLIIIINNNNGGGG MMMMEEEEMMMMOOOORRRRYYYY DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG
     To enable memory debugging, Tcl should be recompiled from scratch with
     TTTTCCCCLLLL____MMMMEEEEMMMM____DDDDEEEEBBBBUUUUGGGG defined.  This will also compile in a non-stub version of
     TTTTccccllll____IIIInnnniiiittttMMMMeeeemmmmoooorrrryyyy to add the mmmmeeeemmmmoooorrrryyyy command to Tcl.

     TTTTCCCCLLLL____MMMMEEEEMMMM____DDDDEEEEBBBBUUUUGGGG must be either left defined for all modules or undefined
     for all modules that are going to be linked together.  If they are not,
     link errors will occur, with either TTTTccccllllDDDDbbbbCCCCkkkkffffrrrreeeeeeee and TTTTccccllll____DDDDbbbbCCCCkkkkaaaalllllllloooocccc or
     TTTTccccllll____CCCCkkkkaaaalllllllloooocccc and TTTTccccllll____CCCCkkkkffffrrrreeeeeeee being undefined.

GGGGUUUUAAAARRRRDDDD ZZZZOOOONNNNEEEESSSS
     When memory debugging is enabled, whenever a call to cccckkkkaaaalllllllloooocccc is made,
     slightly more memory than requested is allocated so the memory debugging
     code can keep track of the allocated memory, and also eight-byte ``guard
     zones'' are placed in front of and behind the space that will be returned
     to the caller.  (The size of the guard zone is defined by the C #define
     GGGGUUUUAAAARRRRDDDD____SSSSIIIIZZZZEEEE in _b_a_s_e_l_i_n_e/_s_r_c/_c_k_a_l_l_o_c._c -- it can be extended if you suspect
     large overwrite problems, at some cost in performance.)  A known pattern
     is written into the guard zones and, on a call to cccckkkkffffrrrreeeeeeee, the guard zones
     of the space being freed are checked to see if either zone has been
     modified in any way.  If one has been, the guard bytes and their new
     contents are identified, and a ``low guard failed'' or ``high guard
     failed'' message is issued.  The ``guard failed'' message includes the
     address of the memory packet and the file name and line number of the
     code that called cccckkkkffffrrrreeeeeeee.  This allows you to detect the common sorts of
     one-off problems, where not enough space was allocated to contain the
     data written, for example.

TTTTHHHHEEEE MMMMEEEEMMMMOOOORRRRYYYY CCCCOOOOMMMMMMMMAAAANNNNDDDD
     mmmmeeeemmmmoooorrrryyyy _o_p_t_i_o_n_s
          The Tcl mmmmeeeemmmmoooorrrryyyy command gives the Tcl developer control of Tcl's
          memory debugging capabilities.  The memory command has several
          suboptions, which are described below.  It is only available when
          Tcl has been compiled with memory debugging enabled.

     mmmmeeeemmmmoooorrrryyyy iiiinnnnffffoooo
          Produces a report containing the total allocations and frees since
          Tcl began, the current packets allocated (the current number of
          calls to cccckkkkaaaalllllllloooocccc not met by a corresponding call to cccckkkkffffrrrreeeeeeee), the
          current bytes allocated, and the maximum number of packets and bytes
          allocated.

     mmmmeeeemmmmoooorrrryyyy ttttrrrraaaacccceeee [oooonnnn||||ooooffffffff]
          Turns memory tracing on or off.  When memory tracing is on, every
          call to cccckkkkaaaalllllllloooocccc causes a line of trace information to be written to
          _s_t_d_e_r_r, consisting of the word _c_k_a_l_l_o_c, followed by the address
          returned, the amount of memory allocated, and the C filename and
          line number of the code performing the allocation, for example...

             cccckkkkaaaalllllllloooocccc 44440000eeee444477778888 99998888 ttttccccllllPPPPrrrroooocccc....cccc 1111444400006666



                                                                        PPPPaaaaggggeeee 3333






MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))                                                      MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))



          Calls to cccckkkkffffrrrreeeeeeee are traced in the same manner, except that the word
          _c_k_a_l_l_o_c is replaced by the word _c_k_f_r_e_e.

     mmmmeeeemmmmoooorrrryyyy vvvvaaaalllliiiiddddaaaatttteeee [oooonnnn||||ooooffffffff]
          Turns memory vaidation on or off.  When memory validation is
          enabled, on every call to cccckkkkaaaalllllllloooocccc or cccckkkkffffrrrreeeeeeee, the guard zones are
          checked for every piece of memory currently in existence that was
          allocated by cccckkkkaaaalllllllloooocccc.  This has a large performance impact and
          should only be used when overwrite problems are strongly suspected.
          The advantage of enabling memory validation is that a guard zone
          overwrite can be detected on the first call to cccckkkkaaaalllllllloooocccc or cccckkkkffffrrrreeeeeeee
          after the overwrite occurred, rather than when the specific memory
          with the overwritten guard zone(s) is freed, which may occur long
          after the overwrite occurred.

     mmmmeeeemmmmoooorrrryyyy ttttrrrraaaacccceeee____oooonnnn____aaaatttt____mmmmaaaalllllllloooocccc _n_n_n
          Enable memory tracing after _n_n_n cccckkkkaaaallllllllooooccccssss have been performed.  For
          example, if you enter mmmmeeeemmmmoooorrrryyyy ttttrrrraaaacccceeee____oooonnnn____aaaatttt____mmmmaaaalllllllloooocccc 111100000000, after the 100th
          call to cccckkkkaaaalllllllloooocccc, memory trace information will begin being displayed
          for all allocations and frees.  Since there can be a lot of memory
          activity before a problem occurs, judicious use of this option can
          reduce the slowdown caused by tracing (and the amount of trace
          information produced), if you can identify a number of allocations
          that occur before the problem sets in.  The current number of memory
          allocations that have occured since Tcl started is printed on a
          guard zone failure.

     mmmmeeeemmmmoooorrrryyyy bbbbrrrreeeeaaaakkkk____oooonnnn____mmmmaaaalllllllloooocccc _n_n_n
          After the nnnnnnnnnnnn allocations have been performed, cccckkkkaaaallllllllooooccccssss output a
          message to this effect and that it is now attempting to enter the C
          debugger.  Tcl will then issue a _S_I_G_I_N_T signal against itself.  If
          you are running Tcl under a C debugger, it should then enter the
          debugger command mode.

     mmmmeeeemmmmoooorrrryyyy ddddiiiissssppppllllaaaayyyy _f_i_l_e
          Write a list of all currently allocated memory to the specified
          file.

DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG DDDDIIIIFFFFFFFFIIIICCCCUUUULLLLTTTT MMMMEEEEMMMMOOOORRRRYYYY CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIIOOOONNNN PPPPRRRROOOOBBBBLLLLEEEEMMMMSSSS
     Normally, Tcl compiled with memory debugging enabled will make it easy to
     isolate a corruption problem.  Turning on memory validation with the
     memory command can help isolate difficult problems.  If you suspect (or
     know) that corruption is occurring before the Tcl interpreter comes up
     far enough for you to issue commands, you can set MMMMEEEEMMMM____VVVVAAAALLLLIIIIDDDDAAAATTTTEEEE define,
     recompile tclCkalloc.c and rebuild Tcl.  This will enable memory
     validation from the first call to cccckkkkaaaalllllllloooocccc, again, at a large performance
     impact.

     If you are desperate and validating memory on every call to cccckkkkaaaalllllllloooocccc and
     cccckkkkffffrrrreeeeeeee isn't enough, you can explicitly call TTTTccccllll____VVVVaaaalllliiiiddddaaaatttteeeeAAAAllllllllMMMMeeeemmmmoooorrrryyyy
     directly at any point.  It takes a _c_h_a_r * and an _i_n_t which are normally
     the filename and line number of the caller, but they can actually be



                                                                        PPPPaaaaggggeeee 4444






MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))                                                      MMMMeeeemmmmoooorrrryyyy((((3333TTTTccccllll))))



     anything you want.  Remember to remove the calls after you find the
     problem.

KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
     ckalloc, ckfree, free, memory, malloc


















































                                                                        PPPPaaaaggggeeee 5555